feat(test): mountTestState/withTestState — one mounted state across several renderRoute calls - #525

Fixes #484.

What

agent-bundle/test now exports mountTestState() and withTestState(): one state owner — the project's state definition plus its notice ledger — mounted once for a whole test, so a journey that records on one event and reads on the next runs against the same state / noticeLedger under every render.

• mountTestState<TState, TEvents>(options?) → MountedTestState with context() ({ state, noticeLedger } to spread into any renderRoute / renderRouteEvents context), read() (typed AgentStateSnapshot<TState>), notices() (the ledger snapshot), close() (idempotent), plus the bare state / noticeLedger handles for a direct dispatch.
• Same driver rules as the per-render mount (render.ts mountState), now shared through one openStateOwner: workspace-durable → disposable sqlite root removed on close(); other lifetimes → memory driver; options.driver overrides and is closed with the mount.
• options.definition mounts an explicit definition (checked typing) instead of the manifest's registered src/state.ts; options.manifest picks an explicit manifest. A manifest without state fails manifest-unavailable; an external definition without a driver fails invalid-input — both name the recovery.
• withTestState(run, options?) is the scoped form (try/finally owned by the helper).
• No render-path change: renderRoute already honours caller-supplied state/noticeLedger and mounts nothing when both are present.

Shape decision: both helpers, since the scoped one is a five-line wrapper; the examples show each style (beforeEach/afterEach with mountTestState, single-test withTestState). read() typing comes from type arguments or a checked options.definition — the generated Register carries route contracts only, no state type; registering the state type via typegen would be a separate change.

Consumer code deleted

• examples/worktree-proximity/tests/route-unit/routes.test.ts: the mkdtemp/createSqliteStateDriver/createGeneratedRuntimeState mount, the per-render requestBindings()/close() pair, and six more requestBindings() pairs used only to read snapshots — replaced with mounted.context(), mounted.read(), mounted.notices(). No more @agent-bundle/runtime/mount or /state/sqlite imports.
• examples/host-test/tests/route-unit/routes.test.ts: same mount and per-render bindings removed (the mkdtemp that remains is for the example's own log dir).
• examples/audiobook-curator/tests/route-unit/state.test.ts: the re-wrapped defineState({ ...shelfStateDefinition, id, lifetime: 'process' }) + createMemoryStateDriver + createAgentStateHandle mount replaced with withTestState; it now renders against the project's real definition and gets a notice ledger too.

Docs

website/docs/{en,zh}/guide/development/testing.mdx: new "One state across several renders" subsection and the route-unit row of the proof-level table. pnpm docs:site:build passes (parity, dead links).

Tests

• New packages/agent-bundle/tests/route-unit/mount-test-state.test.ts (7 tests): state and ledger carried across renders and read back; isolated per-render mounts still work alongside; idempotent close; explicit definition typed read(); caller driver used and closed; scoped close on throw; no-state manifest and external-without-driver refusals.
• pnpm test:route-unit 65/65; pnpm test:unit green except framework-plugin-registration.test.ts (pre-existing on main, fixed by test(build): pass the project root to the composed configs in the plugin-registry test #523) and four load-induced timeouts that pass in isolation; pnpm typecheck clean apart from the same test(build): pass the project root to the composed configs in the plugin-registry test #523 file; pnpm lint clean.
• Touched examples: worktree-proximity (typecheck + test:routes 10/10), host-test (typecheck + test 7/7), audiobook-curator (typecheck + test:routes 31/31).

Changeset

.changeset/484-mount-test-state.md (agent-bundle: patch).

Review status

• 2e4093a1f — Codex reviewed; one P1 thread on render.ts (mountTestState handles were bound only to the mount-wide signal, so a render's own signal did not cancel its in-flight state operations). Addressed in f5e5cd223: a render that receives the mounted handles rebinds the shared owner through requestBindings({ signal }) — the generated request scope's own binding — so its signal cancels its state operations while the owner the other renders share is untouched; request-lifetime owners keep the mount's single binding. Covered by the new "binds each render to its own signal without disturbing the shared owner" test. Docs (en + zh) state the per-render binding.
• Rebased onto main at test(build): pass the project root to the composed configs in the plugin-registry test #523 (picks up the framework-plugin-registration typecheck fix). Awaiting the reviewer on the current head; per this task's rules no PR comments are posted, so the re-review is not requested via @codex review.